---
title: 图表
icon: '#pro/ChartPie'
---

<MetaData
  lang="zh-CN"
  isPro
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-advanced',
      locale: '@univerjs/preset-sheets-advanced/locales/zh-CN',
      style: '@univerjs/preset-sheets-advanced/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs-pro/sheets-chart',
      locale: '@univerjs-pro/sheets-chart/locale/zh-CN',
    }, {
      client: '@univerjs-pro/sheets-chart-ui',
      facade: '@univerjs-pro/sheets-chart-ui/facade',
      locale: '@univerjs-pro/sheets-chart-ui/locale/zh-CN',
      style: '@univerjs-pro/sheets-chart-ui/lib/index.css',
    }],
    server: '否',
  }}
/>

图表是数据可视化的重要工具，可以帮助用户更直观地理解和分析数据。在 Univer Sheets 中，图表功能提供了多种类型的图表，包括柱状图、折线图、饼图等，用户可以根据需要选择合适的图表类型来展示数据。

<PlaygroundFrame lang="zh-CN" slug="sheets/charts" clickToShow />

## 预设模式

图表功能被包含在 `@univerjs/preset-sheets-advanced` 预设中。

### 安装

<Callout>
  @univerjs/preset-sheets-advanced 的 `UniverSheetsAdvancedPreset` 预设在运行时依赖 `UniverSheetsDrawingPreset` 预设，请先安装 @univerjs/preset-sheets-drawing。
</Callout>

```package-install
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### 使用

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsDrawingZhCN, // [!code ++]
      UniverPresetSheetsAdvancedZhCN, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](/guides/pro/license#在预设模式中使用)进行配置。

{/* ### 预设与配置 */}

## 插件模式

### 安装

```package-install
npm install @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
```

### 使用

```typescript
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart' // [!code ++]
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui' // [!code ++]
import SheetsChartUIZhCN from '@univerjs-pro/sheets-chart-ui/locale/zh-CN' // [!code ++]
import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-chart-ui/facade' // [!code ++]

import '@univerjs-pro/sheets-chart-ui/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      SheetsChartZhCN, // [!code ++]
      SheetsChartUIZhCN, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsChartPlugin)
univer.registerPlugin(UniverSheetsChartUIPlugin)
```

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](/guides/pro/license#在插件模式中使用)进行配置。

## 枚举

<details>
  <summary>显示枚举</summary>
  ```typescript
  export enum ChartAttributeBits {
    Stack = 1 << 30,
    PercentStack = 1 << 29 | ChartAttributeBits.Stack,
    Horizontal = 1 << 28,
  }

  export enum ChartTypeBits {
    None = 0,
    Line = 1 << 1,
    Column = 1 << 2,
    ColumnStacked = ChartTypeBits.Column | ChartAttributeBits.Stack,
    ColumnPercentStacked = ChartTypeBits.Column | ChartAttributeBits.PercentStack,
    Bar = 1 << 2 | ChartAttributeBits.Horizontal,
    BarStacked = ChartTypeBits.Bar | ChartAttributeBits.Stack,
    BarPercentStacked = ChartTypeBits.Bar | ChartAttributeBits.PercentStack,
    Pie = 1 << 3,
    Doughnut = 1 << 8 | ChartTypeBits.Pie,
    Area = 1 << 4,
    AreaStacked = ChartTypeBits.Area | ChartAttributeBits.Stack,
    AreaPercentStacked = ChartTypeBits.Area | ChartAttributeBits.PercentStack,
    Radar = 1 << 5,
    Scatter = 1 << 6,
    Combination = 1 << 7,
  }
  ```
</details>

## Facade API

完整 Facade API 类型定义，请查看 [FacadeAPI](https://reference.univer.ai/zh-CN)。

在 Univer Sheets 中，您可以使用 Facade API 来创建、配置和管理图表。Facade API 是一种图表的编程接口，可以帮助您更方便地使用图表功能。

### 插入图表

[`FWorksheet.newChart()`](https://reference.univer.ai/zh-CN/classes/FWorksheet#newchart) 方法用于创建一个图表构建器，返回一个 `FChartBuilderBase` 实例，您可以通过链式调用方法来设置图表的各种属性。

然后调用 `build()` 生成 `IChartBuilderInfo` 对象，通过 [`FWorksheet.insertChart(chartBuildInfo: IChartBuilderInfo)`](https://reference.univer.ai/zh-CN/classes/FWorksheet#insertchart) 方法将图表插入到表格中。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个柱状图，数据源为 A1:D6。
// 开始位置为单元格 B2 的左上角。
// 图表的宽度为 600，高度为 400。
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .setWidth(600)
  .setHeight(400)
  .build()
await fWorksheet.insertChart(chartInfo)
```

以下是 [`FChartBuilderBase`](https://reference.univer.ai/zh-CN/classes/FChartBuilderBase) 上的一些成员方法：

| 方法 | 描述 |
| --- | --- |
| addRange | 指定图表数据源范围 |
| setPosition | 以 row，col 锚点方式设置图表位置 |
| setAbsolutePosition | 以像素方式设置图表位置 |
| setChartType | 设置图表类型 |
| setWidth | 设置图表宽度 |
| setHeight | 设置图标高度 |
| setOptions | 设置图表配置项 |
| setTransposeRowsAndColumns | 行列转换 |
| setTheme | 设置主题 |
| setXAxisTitle | 设置X轴标题 |
| setYAxisTitle | 设置Y轴标题 |
| setRightYAxisTitle | 设置右轴标题 |
| setXAxisTextStyle | 设置X轴标题样式 |
| setYAxisTextStyle | 设置Y轴标题样式 |
| setRightYAxisTextStyle | 设置右轴标题样式 |
| setInvalidValueStrategy | 设置空单元格显示方式 |
| setAxisPointerStyle | 设置指示线样式 |
| setALLSeriesStyle | 设置所有系列样式 |
| setSeriesStyle | 设置系列样式 |
| build | 生成 builder info，用于插入/更新图表 |

目前我们支持以下的配置项，您可以通过查阅 IChartBuildOptions 来获取对应的配置：

<details>
  <summary>显示配置</summary>
  ```typescript
  export interface IChartBuildOptions {
    /**
     * @property {string} [title] The title of the chart.
     */
    title?: {
      /**
       * @property {string} [titlePosition] The position of the chart title.
       */
      position?: TitlePositionEnum
    } & IChartTextStyle
    /**
     * @property {string} [legend] The legend of the chart.
     */
    legend?: {
      /**
       * @property {string} [legendPosition] The position of the legend.The possible values are 'top', 'bottom', 'left', 'right' & 'hide'.
       */
      position?: LegendPositionEnum
      /**
       * @property {number} [fontSize] The font size of the legend.
       */
      fontSize?: number
      /**
       * @property {string} [color] The font color of the legend.
       */
      color?: string
      /**
       * @property {string} [bold] The font style of the legend.
       */
      bold?: boolean
      /**
       * @property {string} [italic] The font weight of the legend.
       */
      italic?: boolean
      /**
       * @property {SelectModeEnum} [selectMode] The select mode of the legend.The possible values are 'single', 'multiple' & 'close'.
       */
      selectMode?: SelectModeEnum
    }
    /**
     * @property {string} [xAxisTitle] The x-axis title of the chart.
     * @example
     * ```typescript
     * chartBuilder.setOptions('xAxisTitle.content', 'xAxis Title text')
     * .setOptions('xAxisTitle.font', 1)
     * .setOptions('xAxisTitle.fontSize', 12)
     * .setOptions('xAxisTitle.fontColor', '#ff0000')
     * .build();
     * ```
     */
    xAxisTitle?: IChartTextStyle
    /**
     * @property {string} [rightYAxisTitle] The right y-axis title of the chart.
     */
    yAxisTitle?: IChartTextStyle
    /**
     * @property {string} [rightYAxisTitle] The right y-axis title of the chart.
     */
    rightYAxisTitle?: IChartTextStyle
    xAxis?: IAxisOptions
    yAxis?: IAxisOptions
    yRightAxis?: IAxisOptions
    axisPointer?: {
      /**
       * @property {string} [indicatorLineType] The line type of the axis pointer.
       */
      indicatorLineType?: string
      /**
       * @property {ChartBorderDashType} [indicatorLineColor] The line color of the axis pointer.The maybe values are 'solid', 'dotted', 'dashed'.
       */
      indicatorLineColor?: ChartBorderDashType
      /**
       * @property {string} [indicatorLabelColor] The line width of the axis pointer.
       */
      indicatorLabelColor?: string
      /**
       * @property {string} [indicatorLabelTextColor] The font color of the axis pointer.
       */
      indicatorLabelTextColor?: string
    }
    allSeriesStyle?: IAllSeriesStyle
    seriesStyleMap?: {
      [id: string]: ISeriesStyle
    }
    /**
     * @property {string} [area] The area of line/area chart.
     */
    area?: {
      lineStyle: AreaLineStyle
    }
    /**
     * @property {string} [backgroundColor] The background color of the chart.
     */
    backgroundColor?: string
    /**
     * @property {string} [borderColor] The border color of the chart.
     */
    borderColor?: string
    /**
     * @property {boolean} [gradientFill] Whether to use gradient fill.This property does not work in line charts.
     */
    gradientFill?: boolean
    /**
     * @property {string} [theme] The theme of the chart.
     */
    theme?: string
    /**
     * @property {InvalidValueType} [invalidValueType] The display mode for empty cells.
     */
    invalidValueType?: InvalidValueType
  }
  ```
</details>

配置项通过 setOptions 方法来设置，有以下两种方式：
  - `setOptions(optionPath, optionVal)`: `setOptions('legend.color', '#ff0000')`
  - `setOptions('', IChartBuildOptions)`: `setOptions('', { legend: { color: '#ff0000', bold: true } })`

<details>
  <summary>创建一个折线图示例</summary>
  ```typescript
  const fWorkbook = univerAPI.getActiveWorkbook()
  const fWorksheet = fWorkbook.getActiveSheet()

  // 创建一个折线图
  const chartInfo = fWorksheet.newChart()
    // 折线图
    .asLineChart()
    // 设置数据源 A1:D6
    .addRange('A1:D6')
    // 设置起始位置 B2 单元格左上角
    .setPosition(1, 1, 0, 0)
    // 设置指示线样式
    .setAxisPointerStyle({
      indicatorLabelColor: '#ff0000',
      indicatorLineType: univerAPI.Enum.ChartBorderDashType.Solid,
      indicatorLineColor: '#00ff00',
      indicatorLabelTextColor: '#0000ff',
    })
    // 设置数据点大小 10
    .setDataPointSize(10)
    // 设置数据点形状为圆形
    .setDataPointShape(univerAPI.Enum.LinePointShape.CIRCLE)
    // 生成 builder info
    .build()
  const fChart = await fWorksheet.insertChart(chartInfo)

  // 3 秒后更新图表
  setTimeout(() => {
    if (fChart) {
      // 获取第一个系列数据
      const first = fChart.getSeriesData()[0]
      // 设置第一个系列颜色为红色
      const newChartInfo = fWorksheet.newChart(fChart)
        .setSeriesStyle(first.index, {
          color: '#ff0000',
        })
        .build()
      // 更新图表
      fSheet.updateChart(newChartInfo)
    }
  }, 3000)
  ```
</details>

目前我们还提供了以下的 builder 来创建对应的图表，这些 builder 都可以通过类似 `fWorkSheet.newChart().asLineChart()` 来创建，他们派生自 `FChartBuilderBase` 并且具有一些特有的配置：

```typescript
const lineChartBuilder = fWorkSheet.newChart().asLineChart()
const pieChartBuilder = fWorkSheet.newChart().asPieChart()
const radarChartBuilder = fWorkSheet.newChart().asRadarChart()

// 也可以通过下面的方式来创建
const chartBuilder = fWorkSheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
```

- [LineChartBuilder](https://reference.univer.ai/zh-CN/classes/LineChartBuilder)

| 方法 | 描述 |
| --- | --- |
| setLineStyle | 设置折线的平滑度，'line'- 折线 , 'smooth'- 平滑， 'step' -阶梯 |
| setDataPointShape | 设置数据点形状，可以通过 LinePointShape 来查看支持的形状类型 |
| setDataPointColor | 设置数据点颜色 |
| setDataPointSize | 设置数据点大小 |
| build | 生成 builder info，用于插入/更新图表 |

- [PieChartBuilder](https://reference.univer.ai/zh-CN/classes/PieChartBuilder)

| 方法 | 描述 |
| --- | --- |
| setDoughnutHole | 设置饼图空心大小，该参数范围为 0-1 |
| setBorderColor | 设置饼图扇区的色值 |
| setHasPaddingAngle | 设置饼图扇区的是否有夹角（分离） |
| setIsHalfPie | 是不是半饼 |
| setRosePie | 是不是玫瑰图 |
| setShowLabelLine | 显示标签线 |
| build | 生成 builder info，用于插入/更新图表 |

- [RadarChartBuilder](https://reference.univer.ai/zh-CN/classes/RadarChartBuilder)

| 方法 | 描述 |
| --- | --- |
| setShape | 设置雷达图默认形状，目前支持的值为：'polygon'-多边形，'circle'-圆形 |
| setFill | 是否填充雷达图 |
| build | 生成 builder info，用于插入/更新图表 |

### 获取图表

[`FWorksheet.getCharts()`](https://reference.univer.ai/zh-CN/classes/FWorksheet#getcharts) 方法用于获取当前工作表中的所有图表，返回一个 `FChart[]` 数组。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 获取当前工作表中的所有图表
const charts = fWorksheet.getCharts()
```

以下是 [`FChart`](https://reference.univer.ai/zh-CN/classes/FChart) 上的一些成员方法：

| 方法 | 描述 |
| --- | --- |
| getRange | 获取图表数据源范围 |
| getSeriesData | 获取图表系列数据 |
| getCategoryData | 获取图表类别数据 |
| updateRange | 更新图表数据源范围 |

### 更新图表

[`FWorksheet.updateChart(chartBuildInfo: IChartBuilderInfo)`](https://reference.univer.ai/zh-CN/classes/FWorksheet#updatechart) 方法用于更新图表，传入一个 `IChartBuilderInfo` 对象，用于更新图表的配置。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个柱状图，数据源为 A1:D6.
// 起始位置为单元格 B2 的左上角.
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .build()
await fWorksheet.insertChart(chartInfo)

// 获取当前工作表中的所有图表
const charts = fWorksheet.getCharts()

// 3 秒后更新第一个图表
setTimeout(() => {
  const newChartInfo = fWorksheet.newChart(charts[0])
    .asLineChart()
    .setOptions('legend.position', univerAPI.Enum.LegendPositionEnum.Right)
    .build()
  fWorksheet.updateChart(newChartInfo)
}, 3000)
```

### 删除图表

[`FWorksheet.removeChart(chart: FChart)`](https://reference.univer.ai/zh-CN/classes/FWorksheet#removechart) 方法用于删除图表，传入一个 `FChart` 对象，用于删除指定的图表。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 创建一个柱状图，数据源为 A1:D6.
// 起始位置为单元格 B2 的左上角.
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .build()
await fWorksheet.insertChart(chartInfo)

// 获取当前工作表中的所有图表
const charts = fWorksheet.getCharts()

// 3 秒后删除第一个图表
setTimeout(async () => {
  await fWorksheet.removeChart(charts[0])
  fWorksheet.getCharts()
}, 3000)
```

### 图表主题

[`FWorksheet.registerChartTheme(themeName: string, theme: IEchartTheme)`](https://reference.univer.ai/zh-CN/classes/FWorksheet#registercharttheme) 方法用于注册图表主题，传入一个主题名称和主题对象，用于注册自定义主题。

Univer chart 是基于 echarts 的图表库实现的，因此可以借助 echart 的主题构建工具来构建您的[自定制主题](https://echarts.apache.org/zh/theme-builder.html)。
您可以在该网站构建您自己的主题并下载成为配置文件，使用以下 API 来使用您的自定义主题：

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 注册您的主题
const theme = { // 您的主题配置
  version: 1,
  themeName: 'myTheme',
  theme: {
    // ... 为了简洁，省略了一些代码
    color: [
      '#893448',
      '#d95850',
      '#eb8146',
      '#ffb248',
      '#f2d643',
      '#ebdba4',
    ],
    // ... 为了简洁，省略了一些代码
    visualMapColor: [
      '#893448',
      '#d95850',
      '#eb8146',
      '#ffb248',
      '#f2d643',
      'rgb(247,238,173)',
    ],
    // ... 为了简洁，省略了一些代码
    axes: [],
    // ... 为了简洁，省略了一些代码
  },
}
fWorksheet.registerChartTheme('myTheme', theme)

// 使用您的主题创建一个折线图
const chartInfo = fWorksheet.newChart()
  .asLineChart()
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .setTheme('myTheme')
  .build()
await fWorksheet.insertChart(chartInfo)
```
